# Usage

Pulsars are best suited for situations where you need to draw attention to a part in the UI, and want to do it contextually and gently without too much of a distraction or removal from the main experience of using the app.

Specifically, a pulsar is optional - the user can simply ignore the pulsing dot and continue using the app as they would. If they happen across it, the pulsar can provide a helpful tip on hover or can even guide them to their next action.

It is also important to note that pulsars are not meant to be a permanent part of the UI. They should be used judiciously and with purpose. If pulsars are there all the time, and in every part of the app, they will lose their meaning.

## Basic Usage

In order to render the pulsar in-line over your text or other component, we recommend using a [`Pane`](/foundations/layers#pane_component) with `position="relative"` and `display="inline-block"` set.

```jsx
<Pane position="relative" display="inline-block">
  <Text>Pulsar Example</Text>
  <Pulsar />
</Pane>
```

## Use with a Tooltip

A [`Tooltip`](/components/tooltip) can be used to provide additional context for the user.

```jsx
<Pane position="relative" display="inline-block">
  <Text>Pulsar Example</Text>
  <Tooltip content="This feature is available in beta and is subject to change.">
    <Pulsar />
  </Tooltip>
</Pane>
```

## Positioning

Pulsars can be positioned just like a [`Tooltip`](/components/tooltip) or [`Popover`](/components/popover).

```jsx
<Pane padding={40} display="flex" flexDirection="column" gap={32} alignItems="flex-start">
  <Pane position="relative" display="inline-block">
    <Text>Pulsar Top Left</Text>
    <Pulsar position={Position.TOP_LEFT} />
  </Pane>
  <Pane position="relative" display="inline-block">
    <Text>Pulsar Top Right</Text>
    <Pulsar position={Position.TOP_RIGHT} />
  </Pane>
  <Pane position="relative" display="inline-block">
    <Text>Pulsar Bottom Right</Text>
    <Pulsar position={Position.BOTTOM_RIGHT} />
  </Pane>
  <Pane position="relative" display="inline-block">
    <Text>Pulsar Bottom Left</Text>
    <Pulsar position={Position.BOTTOM_LEFT} />
  </Pane>
</Pane>
```

## Sizing

Use the `size` prop to control how large the Pulsar is.

```jsx
<Pane position="relative" display="inline-block">
  <Text>Pulsar Example</Text>
  <Pulsar size={16} />
</Pane>
```
